KCFindFirstItem

KCFindFirstItem
Header:	Keychain.h		Carbon status:	Under Evaluation

Finds the first keychain item in a specified keychain that matches specified attributes.

OSStatus KCFindFirstItem (
    KCRef keychain, 
    const KCAttributeList *attrList, 
    KCSearchRef *search, 
    KCItemRef *item
);

Parameter descriptions

keychain: A reference to the keychain that you wish to search. If you pass a locked keychain, the Unlock Keychain dialog box is displayed. If you pass NULL, KCFindFirstItem search all unlocked keychains.
attrList: A pointer to a list of 0 or more structures containing information about the keychain item attributes to be matched. Pass NULL to match any attribute.
search: On return, a pointer to a reference to the current search criteria.
item: On return, a pointer to the first matching keychain item.

function result: A result code. The result code errKCNoDefaultKeychain indicates that no default keychain could be found. The result code errKCItemNotFound indicates that no matching keychain item was found. The result code errKCNoSuchAttr indicates that the specified attribute is undefined for this item class.

DISCUSSION

The KCFindFirstItem function returns a reference to the first keychain item in a keychain that matches a list of attributes. KCFindFirstItem also returns a reference to the search criteria used. You should pass the returned search criteria in the searchRef parameter of the function KCFindNextItem.

KCFindFirstItem will automatically call the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the item you are searching for is currently locked.

SPECIAL CONSIDERATIONS

When you are completely finished with a search, you should the functions KCReleaseItem and KCReleaseSearch to release the memory occupied by the keychain item and search criteria reference.

VERSION NOTES

Available beginning with Keychain Manager 1.0.